.TH funct "3rtapi" "2006-10-12" "LinuxCNC Documentation" "RTAPI"
.SH NAME

rtapi_atomic \- subset of C11 <stdatomic.h>

.SH SYNTAX
.HP
#include <rtapi_atomic.h>
.HP
enum memory_order { ... };
.HP
#define atomic_store(obj, desired)...
.HP
#define atomic_store_explicit(obj, desired, order)...
.HP
#define atomic_load(obj)...
.HP
#define atomic_load_explicit(obj, order)...

.SH  ARGUMENTS
.IP "\fBvolatile A*\fR \fIobj\fR"
A pointer to a volatile object that is the destination of the store or the
source of the load.  The pointer must have an appropriate type and alignment
such that the underlying store or load operation itself is atomic; at a
minimum, a properly aligned "int" may be assumed to be such a type.  Improper
size or alignment are undiagnosed errors.
.IP "\fBC\fR \fIdesired\fR"
The value to be stored in the object.  "*obj = desired" must be well-formed.
.IP "\fBmemory_order\fR order"
The required memory ordering semantic.

.SH DESCRIPTION
This header provides at least the subset of C11's <stdatomic.h> given above.
When there is an ordering requirement for multiple values read or written in RTAPI
shared memory areas by other threads of execution, including the values of HAL
pins and parameters, these functions (or function-like macros) are the only way
to ensure the ordering requirement is obeyed.  Otherwise, according to
architecture-specific rules, loads and stores may be reordered from their
normal source code order.

For example, to leave a message in a shared memory area from one thread and
retrieve it from another, the writer must use an atomic store for the "message
is complete" variable, and the reader must use an atomic load when checking that variable:

.RS
.EX
// producer
*message = 42;
atomic_store_explicit(message_ready, 1, memory_order_release);

// consumer
while(atomic_load_explicit(message_ready, memory_order_acquire) == 0) sched_yield();
printf("message was %d\\n", *message); // must print 42
.EE
.RE

.SH REALTIME CONSIDERATIONS
May be called from any code.
.SH RETURN VALUE
.B atomic_load
and
.B atomic_load_explicit
return the value pointed to by the
.I obj
argument.

.B atomic_store
and
.B atomic_store_explicit
have no return value.

.SH SEE ALSO
.BR <stdatomic.h> " (C11), " <rtapi_bitops.h> " (for other atomic memory operations supported by rtapi)"

